Mac Easy 2010 May

home *** CD-ROM | disk | FTP | other *** search

/ Mac Easy 2010 May / Mac Life Ubuntu.iso / casper / filesystem.squashfs / usr / lib / perl5 / Glib / BookmarkFile.pod next >

Wrap

Text File | 2008-11-04 | 13.1 KB | 753 lines

=head1 NAME Glib::BookmarkFile - Parser for bookmark files =for position SYNOPSIS =head1 SYNOPSIS use Glib; $date .= $_ while (<DATA>); $b = Glib::BookmarkFile->new; $b->load_from_data($data); $uri = 'file:///some/path/to/a/file.txt'; if ($b->has_item($uri)) { $title = $b->get_title($uri); $desc = $b->get_description($uri); print "Bookmark for `$uri' ($title):\n"; print " $desc\n"; } 0; __DATA__ <?xml version="1.0" encoding="UTF-8"?> <xbel version="1.0" xmlns:bookmark="http://www.freedesktop.org/standards/desktop-bookmarks" xmlns:mime="http://www.freedesktop.org/standards/shared-mime-info"> <bookmark href="file:///tmp/test-file.txt" added="2006-03-22T18:54:00Z" modified="2006-03-22T18:54:00Z" visited="2006-03-22T18:54:00Z"> <title>Test File</title> <desc>Some test file</desc> <info> <metadata owner="http://freedesktop.org"> <mime:mime-type type="text/plain"/> <bookmark:applications> <bookmark:application name="Gedit" exec="gedit %u" timestamp="1143053640" count="1"/> </bookmark:applications> </metadata> </info> </bookmark> </xbel> =for position DESCRIPTION =head1 DESCRIPTION B<Glib::BookmarkFile> lets you parse, edit or create files containing lists of bookmarks to resources pointed to by URIs, with some meta-data bound to them, following the Desktop Bookmark Specification. The recent files support inside GTK+ uses this type of files to store the list of recently used files. The syntax of bookmark files is described in detail in the Desktop Bookmarks Specification, here is a quick summary: bookmark files use a subclass of the XML Bookmark Exchange Language (XBEL) document format, defining meta-data such as the MIME type of the resource pointed by a bookmark, the list of applications that have registered the same URI and the visibility of the bookmark. =cut =for object Glib::BookmarkFile Parser for bookmark files =cut =head1 METHODS =head2 bookmarkfile = Glib::BookmarkFile-E<gt>B<new> =over =back =head2 $bookmark_file-E<gt>B<add_application> ($uri, $name, $exec) =over =over =item * $uri (string) =item * $name (string or undef) =item * $exec (string or undef) =back Adds the application with $name and $exec to the list of applications that have registered a bookmark for $uri into $bookmark_file. Every bookmark inside a C<Glib::BookmarkFile> must have at least an application registered. Each application must provide a name, a command line useful for launching the bookmark, the number of times the bookmark has been registered by the application and the last time the application registered this bookmark. If $name is undef, the name of the application will be the same returned by Glib::get_application_name(); if $exec is undef, the command line will be a composition of the program name as returned by Glib::get_prgname() and the "%u" modifier, which will be expanded to the bookmark's URI. This function will automatically take care of updating the registrations count and timestamping in case an application with the same $name had already registered a bookmark for $uri inside the bookmark file. If no bookmark for $uri is found one is created. =back =head2 $bookmark_file-E<gt>B<add_group> ($uri, $group) =over =over =item * $uri (string) =item * $group (string) =back Adds $group to the list of groups to which the bookmark for $uri belongs to. If no bookmark for $uri is found one is created. =back =head2 unix timestamp = $bookmark_file-E<gt>B<get_added> ($uri) =over =over =item * $uri (string) =back =for apidoc __gerror__ Gets the time the bookmark for $uri was added to $bookmark_file. =back =head2 Glib::BookmarkFile::set_added ($bookmark_file, $uri, $value) =over =over =item * $bookmark_file (Glib::BookmarkFile) =item * $uri (string) =item * $value (unix timestamp) =back Sets the time the bookmark for $uri was added. If no bookmark for $uri is found one is created. =back =head2 ($exec, $count, $stamp) = $bookmark_file->B<get_app_info> ($uri, $name) =over =over =item * $uri (string) =item * $name (string) =back Gets the registration informations of $name for the bookmark for $uri. See Glib::BookmarkFile::set_app_info() for more informations about the returned data. May croak with a L<Glib::Error> in $@ on failure. =back =head2 $bookmark_file-E<gt>B<set_app_info> ($uri, $name, $exec, $count, $stamp) =over =over =item * $uri (string) =item * $name (string) =item * $exec (string) =item * $count (integer) =item * $stamp (unix timestamp) =back Sets the meta-data of application $name inside the list of applications that have registered a bookmark for $uri inside $bookmark_file. You should rarely use this method; use Glib::BookmarkFile::add_application() and Glib::BookmarkFile::remove_application() instead. $name can be any UTF-8 encoded string used to identify an application. $exec can have one of these two modifiers: "%f", which will be expanded as the local file name retrieved from the bookmark's URI; "%u", which will be expanded as the bookmark's URI. The expansion is done automatically when retrieving the stored command line using the Glib::BookmarkFile::get_app_info() method. $count is the number of times the application has registered the bookmark; if it is < 0, the current registration count will be increased by one, if it is 0, the application with $name will be removed from the list of registered applications. $stamp is the Unix time of the last registration, as returned by time(); if it is -1, the current time will be used. If you try to remove an application by setting its registration count to zero, and no bookmark for $uri is found, %FALSE is returned and an exception is fired. May croak with a L<Glib::Error> in $@ on failure. =back =head2 list = $bookmark_file->B<get_applications> ($uri) =over =over =item * $uri (string) =back Retrieves the names of the applications that have registered the bookmark for $uri. May croak with a L<Glib::Error> in $@ on failure. =back =head2 $bookmark_file->B<get_description> ($uri) =over =over =item * $uri (string) =back Gets the description of the bookmark for $uri. May croak with a L<Glib::Error> in $@ on failure. =back =head2 $bookmark_file-E<gt>B<set_description> ($uri, $description) =over =over =item * $uri (string) =item * $description (string) =back Sets the description of the bookmark for $uri. If no bookmark for $uri is found one is created. =back =head2 list = $bookmark_file-E<gt>B<get_groups> ($uri) =over =over =item * $uri (string) =back Retrieves the list of group names of the bookmark for $uri. May croak with a L<Glib::Error> in $@ on failure. =back =head2 $bookmark_file-E<gt>B<set_groups> ($uri, ...) =over =over =item * $uri (string) =item * ... (list) one or more group names =back Sets a list of group names for the item with URI $uri. Each previously set group name list is removed. If no bookmark for $uri is found one is created. =back =head2 boolean = $bookmark_file-E<gt>B<has_application> ($uri, $name) =over =over =item * $uri (string) =item * $name (string) =back Checks whether the bookmark for $uri inside $bookmark_file has been registered by application $name. May croak with a L<Glib::Error> in $@ on failure. =back =head2 boolean = $bookmark_file-E<gt>B<has_group> ($uri, $group) =over =over =item * $uri (string) =item * $group (string) =back Checks whether $group appears in the list of groups to which the bookmark for $uri belongs to. May croak with a L<Glib::Error> in $@ on failure. =back =head2 boolean = $bookmark_file-E<gt>B<has_item> ($uri) =over =over =item * $uri (string) =back Looks whether the bookmark file has a bookmark for $uri. =back =head2 ($href, $mime_type) = $bookmark_file->B<get_icon> ($uri) =over =over =item * $uri (string) =back Gets the icon of the bookmark for $uri. May croak with a L<Glib::Error> in $@ on failure. =back =head2 $bookmark_file-E<gt>B<set_icon> ($uri, $href, $mime_type) =over =over =item * $uri (string) =item * $href (string or undef) =item * $mime_type (string or undef) =back Sets the icon for the bookmark for $uri. If $href is undef, unsets the currently set icon. =back =head2 boolean = $bookmark_file-E<gt>B<get_is_private> ($uri) =over =over =item * $uri (string) =back May croak with a L<Glib::Error> in $@ on failure. =back =head2 $bookmark_file-E<gt>B<set_is_private> ($uri, $is_private) =over =over =item * $uri (string) =item * $is_private (boolean) =back =back =head2 $bookmark_file-E<gt>B<load_from_data> ($buf) =over =over =item * $buf (scalar) =back Parses a string containing a bookmark file structure. May croak with a L<Glib::Error> in $@ on failure. =back =head2 ($full_path) = $bookmark_file->B<load_from_data_dirs> ($file) =over =over =item * $file (localized file name) =back Parses a bookmark file, searching for it inside the data directories. If a file is found, it returns the full path. May croak with a L<Glib::Error> in $@ on failure. =back =head2 $bookmark_file-E<gt>B<load_from_file> ($file) =over =over =item * $file (localized file name) =back Parses a bookmark file. May croak with a L<Glib::Error> in $@ on failure. =back =head2 string = $bookmark_file-E<gt>B<get_mime_type> ($uri) =over =over =item * $uri (string) =back Gets the MIME type of the bookmark for $uri. May croak with a L<Glib::Error> in $@ on failure. =back =head2 $bookmark_file-E<gt>B<set_mime_type> ($uri, $mime_type) =over =over =item * $uri (string) =item * $mime_type (string) =back Sets the MIME type of the bookmark for $uri. If no bookmark for $uri is found one is created. =back =head2 unix timestamp = $bookmark_file-E<gt>B<get_modified> ($uri) =over =over =item * $uri (string) =back =for apidoc __gerror__ Gets the time the bookmark for $uri was last modified. =back =head2 Glib::BookmarkFile::set_modified ($bookmark_file, $uri, $value) =over =over =item * $bookmark_file (Glib::BookmarkFile) =item * $uri (string) =item * $value (unix timestamp) =back Sets the time the bookmark for $uri was last modified. If no bookmark for $uri is found one is created. =back =head2 $bookmark_file-E<gt>B<move_item> ($old_uri, $new_uri) =over =over =item * $old_uri (string) =item * $new_uri (string or undef) =back Changes the URI of a bookmark item from $old_uri to $new_uri. Any existing bookmark for $new_uri will be overwritten. If $new_uri is undef, then the bookmark is removed. May croak with a L<Glib::Error> in $@ on failure. =back =head2 $bookmark_file-E<gt>B<remove_application> ($uri, $name) =over =over =item * $uri (string) =item * $name (string) =back Removes application registered with $name from the list of applications that have registered a bookmark for $uri inside $bookmark_file. May croak with a L<Glib::Error> in $@ on failure. =back =head2 $bookmark_file-E<gt>B<remove_group> ($uri, $group) =over =over =item * $uri (string) =item * $group (string) =back Removes $group from the list of groups to which the bookmark for $uri belongs to. May croak with a L<Glib::Error> in $@ on failure. =back =head2 $bookmark_file-E<gt>B<remove_item> ($uri) =over =over =item * $uri (string) =back Removes the bookmark for $uri from the bookmark file. May croak with a L<Glib::Error> in $@ on failure. =back =head2 integer = $bookmark_file-E<gt>B<get_size> =over Gets the number of bookmarks inside the bookmark file. =back =head2 $bookmark_file->B<get_title> ($uri, $title) =over =over =item * $uri (string) =back Gets the title of the bookmark for $uri. May croak with a L<Glib::Error> in $@ on failure. =back =head2 $bookmark_file-E<gt>B<set_title> ($uri, $title) =over =over =item * $uri (string) =item * $title (string) =back Sets the title of the bookmark for $uri. If no bookmark for $uri is found one is created. =back =head2 string = $bookmark_file-E<gt>B<to_data> =over Returns the bookmark file as a string. May croak with a L<Glib::Error> in $@ on failure. =back =head2 $bookmark_file-E<gt>B<to_file> ($file) =over =over =item * $file (localized file name) =back Saves the contents of a bookmark file into a file. The write operation is guaranteed to be atomical by writing the contents of the bookmark file to a temporary file and then moving the file to the target file. May croak with a L<Glib::Error> in $@ on failure. =back =head2 list = $bookmark_file->B<get_uris> =over Returns the URI of all the bookmarks in the bookmark file. =back =head2 unix timestamp = $bookmark_file-E<gt>B<get_visited> ($uri) =over =over =item * $uri (string) =back =for apidoc __gerror__ Gets the time the bookmark for $uri was last visited. =back =head2 Glib::BookmarkFile::set_visited ($bookmark_file, $uri, $value) =over =over =item * $bookmark_file (Glib::BookmarkFile) =item * $uri (string) =item * $value (unix timestamp) =back Sets the time the bookmark for $uri was last visited. If no bookmark for $uri is found one is created. =back =head1 SEE ALSO L<Glib> =head1 COPYRIGHT Copyright (C) 2003-2008 by the gtk2-perl team. This software is licensed under the LGPL. See L<Glib> for a full notice. =cut